|
|
|
| |
WebLogic Server Container-Managed Persistence Services
EJB 2.0 Persistence Features and Changes
"get" and "set" method restrictions
EJB QL requirement for EJB 2.0 beans
isModified() not required for CMP beans
EJB QL conditional expressions
weblogic-cmp-rdbms-jar.xml Requirement
This section describes the new container-managed persistence services available with the EJB 2.0 for BEA WebLogic Server container. This information supplements the basic discussion of WebLogic RDBMS-based persistence services in Persistence Services.
EJB 2.0 Persistence Features and Changes
The EJB 2.0 specification places new requirements on entity EJB finder methods and field accessor methods, and introduces a new, portable query language for creating finders. This section summarizes those features. See the complete EJB 2.0 specification for details.
Finder signature requirements
The EJB 2.0 specification provides additional requirements for specifying finder methods in EJBHome. Each finder method must be prefixed by ejbFind and must now be declared as abstract as well as public. For example:
public abstract Account ejbFindByPrimaryKey(String primarykey)
throws FinderException
Also, in the EJB implementation class the finder method must return the actual Java type of the primary key (for ejbFindByPrimaryKey):
public abstract java.lang.String ejbFindByPrimaryKey(String primarykey)
throws FinderException
For multi-object finders, finder methods in the EJB implementation class must return java.util.Collection, as defined in the EJB 2.0 specification. WebLogic Server also supports java.util.Enumeration for multi-object finders.
See also Required changes for EJB 1.1 compliance for requirements introduced by the EJB 1.1 specification.
"get" and "set" method restrictions
The EJB 2.0 specification standardizes the "get" and "set" methods that a container uses for reading and modifying container-managed fields. These container-generated classes must begin with "get" or "set" and use the actual name of a persistent field defined in ejb-jar.xml. The methods are also declared as public, protected, and abstract.
The EJB 2.0 specification prohibits exposing the container "get" and "set" methods in the public interfaces of the EJB. Therefore, if you are upgrading EJBs to run in the EJB 2.0 container, make sure that those EJBs do not contain client methods that match the signatures of container-generated "get" and "set" methods. For example, if you define a cmp-field named "AccountType," you cannot also define a setAccountType() method in the EJB's remote interface.
EJB QL requirement for EJB 2.0 beans
The deployer must define each finder query for EJB 2.0 entity beans using an EJB QL query string.
You cannot use WebLogic Query Language (WLQL) with entity EJBs that use EJB 2.0 features, or that use EJB 2.0 deployment files. If you want to use WLQL, the entity EJB and its deployment files must be based on the EJB 1.1 specification. See Using WebLogic Server Persistence for more information on WLQL.
isModified() not required for CMP beans
The isModified() method is no longer required for CMP entity EJBs based on the EJB 2.0 specification. When you deploy EJB 2.0 entity beans with container-managed persistence, WebLogic Server automatically detects which EJB fields have been modified during a transaction, and writes only those fields to the underlying datastore.
You can still use isModified() for entity EJBs in the EJB 2.0 container that use bean-managed persistence. See is-modified-method-name for more information.
The EJB 2.0 specification introduces EJB QL as a portable query language for creating entity EJB finders. EJB QL is a SQL-like language that uses a single WHERE clause to select one or more entity EJB objects. The search space for an EJB QL query consists of the EJB's schema as defined in ejb-jar.xml (the bean's collection of container managed fields and their associated database columns). Because EJB QL is portable among containers, EJB QL strings are defined in ejb-jar.xml rather than in weblogic-cmp-rdbms-jar.xml.
Basic syntax
The basic syntax of an EJB QL query consists of an optional FROM clause followed by a WHERE clause.
Because this version of the WebLogic Server EJB 2.0 container does not support relationships, the FROM is also unsupported, and you must omit it from all EJB QL finder queries.
The WHERE clause defines conditions that limit the result set in a similar manner to WebLogic Query Language (WLQL). The remaining sections focus on the EJB QL clauses and operators that you can specify in the WHERE clause.
Note: Because EJB QL queries may contain ">" and "<" characters, always specify the entire EJB QL string within the CDATA tag to avoid confusing the query syntax with XML elements.
EJB QL String literals
As with WLQL, EJB QL designates literal string values by enclosing them within single quotes. To represent a single quote as part of a literal string, use two consecutive single quotes, as in:
WHERE accountType = 'partner''s'
Entity EJB field references
In this Beta version of the WebLogic Server EJB 2.0 container, you must refer to entity EJB fields in EJB QL using unqualified field names. You cannot use qualified field names as mentioned in the EJB 2.0 specification.
For example, after defining EJB fields in your XML deployment files, always use an unqualified field name such as "accountId," rather than "AccountBean.accountID," in EJB QL queries.
Reserved words
This Beta version of the WebLogic Server EJB 2.0 container does not support using quoted names to distinguish EJB QL reserved words from literals in an EJB QL string. Make sure that EJB field names do not match EJB QL reserved words as listed in the EJB 2.0 specification.
Finder parameter placeholders
EJB QL enables you to represent finder method parameters using the convention ?n where n indicates the number of the parameter in the associated finder method. In EJB QL, the first finder parameter is represented by ?1.
Note: If you are familiar with WLQL, be extra careful when converting WLQL strings that contain parameter placeholders. In WLQL, the first finder parameter is represented by 0 (as in $0), whereas in EJB QL the parameter is represented by 1 (?1).
EJB QL operators
EJB QL uses many of the same logical and arithmetic operators used in WLQL. See Migrating from WLQL to EJB QL for a list of WLQL operators and their EJB QL counterparts. See the EJB 2.0 specification for more detailed information about all EJB QL operators.
EJB QL conditional expressions
The following summarizes conditional expressions that you can use in the WHERE clause of an EJB QL query. For more details on using EJB QL, see the EJB 2.0 specification:
|
EJB QL Expression |
Function |
Sample Syntax |
|---|---|---|
|
[NOT] BETWEEN |
Selects values that are between (or are not between) a range of values. |
WHERE accountId BETWEEN 1000 and 2000 |
|
[NOT] IN |
Selects EJBs that match those in a specified list of string literals. Note that the specified list must contain only string literals. |
WHERE accountId IN ('1000', '1020', '1025') |
|
[NOT] LIKE |
Selects values based on wildcard symbol (%) in the supplied text_string |
WHERE accountType LIKE `custom%' |
|
IS [NOT] NULL |
Tests for NULL values |
WHERE accountId IS NOT NULL |
Migrating from WLQL to EJB QL
If you have used previous versions of WebLogic Server, you may already have container-managed entity EJBs that utilize WLQL for finder methods. This section provides a quick reference to common WLQL operations, and explains how to express those operations using EJB QL. See the EJB 2.0 specification for a complete discussion of WLQL syntax.
|
Sample WLQL Syntax |
Equivalent EJB QL Syntax |
|---|---|
|
(= operand1 operand2) |
WHERE operand1 = operand2 |
|
(< operand1 operand2) |
WHERE operand1 < operand2 |
|
(> operand1 operand2) |
WHERE operand1 > operand2 |
|
(<= operand1 operand2) |
WHERE operand1 <= operand2 |
|
(>= operand1 operand2) |
WHERE operand1 >= operand2 |
|
(! operand) |
WHERE operand NOT value |
|
(& operand) |
WHERE expression1 AND expression2 |
|
(| operand) |
WHERE expression1 OR expression2 |
|
(like text_string%) |
WHERE operand LIKE `text_string%' |
|
(isNull operand) |
WHERE operand IS NULL |
|
(isNotNull operand) |
WHERE operand IS NOT NULL |
EJB QL examples
The following excerpts show sample EJB QL strings from the ejb-jar.xml file.
This example returns a collection of AccountBean EJBs whose balance values are greater than the parameter passed to the findBigAccounts method:
<query>
<query-method>
<method-name>findBigAccounts</method-name>
<method-params>
<method-param>double</method-param>
</method-params>
</query-method>
<ejb-ql>
<![CDATA[WHERE balance > ?1]]>
</ejb-ql>
</query>
The following ejb-ql element returns a collection of EJBs whose balance is 1020 or 1025:
<ejb-ql><![CDATA[WHERE accountType IN ('partners', 'channels')]]></ejb-ql>
The following ejb-ql element returns a collection of EJBs whose accountType field is NULL:
<ejb-ql><![CDATA[WHERE accountType IS NULL]]></ejb-ql>
weblogic-cmp-rdbms-jar.xml Requirement
The DTD for the weblogic-cmp-rdbms-jar.xml file has not changed for this Beta release of the WebLogic Server EJB 2.0 container. For this reason, you must still include a finder-list parameter in weblogic-cmp-rdbms-jar.xml, even though the actual finders are read from ejb-jar.xml as required by the EJB 2.0 specification.
Note, however, that WebLogic Server ignores the contents of finder-list in weblogic-cmp-rdbms-jar.xml for this Beta release of the EJB 2.0 container.
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|